Add configurable UUID conversion for non-AWS SQS-compatible services by jm0514 · Pull Request #1433 · awspring/spring-cloud-aws

jm0514 · 2025-08-09T09:15:57Z

Add configurable UUID conversion for non-AWS SQS-compatible services

📢 Type of change

Bugfix
New feature
Enhancement
Refactoring

📜 Description

Added configurable support for SQS-compatible cloud services (like Yandex Message Queue) that use non-UUID MessageId formats. The framework now supports both UUID and non-UUID MessageId handling through a new configuration option.

Configuration:

# For AWS SQS (default behavior)
spring.cloud.aws.sqs.convert-message-id-to-uuid=true

# For non-AWS SQS-compatible services (Yandex, etc.)
spring.cloud.aws.sqs.convert-message-id-to-uuid=false

💡 Motivation and Context

Solves #814

💚 How did you test it?

Unit Tests: Added comprehensive tests for SqsHeaderMapper and MessageHeaderUtils

📝 Checklist

I reviewed submitted code
I added tests to verify changes
I updated reference documentation to reflect the change
All tests passing
No breaking changes

🔮 Next steps

maciejwalkowiak · 2025-08-22T13:38:19Z

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/support/converter/SqsHeaderMapper.java

+			accessor.setHeader(SqsHeaders.SQS_AWS_MESSAGE_ID_HEADER, source.messageId());
+			MessageHeaders messageHeaders = accessor.toMessageHeaders();
+			logger.trace("Mapped headers {} for message {}", messageHeaders, source.messageId());
+			return new MessagingMessageHeaders(messageHeaders, UUID.randomUUID());


Passing a random UUID does not feel right. Perhaps MessagingMessageHeaders can have id set as String instead of UUID? cc @tomazfernandes

Thanks for the suggestion! Updated to generate UUID from Message ID instead of random UUID.

tomazfernandes · 2025-09-02T20:52:52Z

Hey @jm0514, thanks for the PR!

Perhaps MessagingMessageHeaders can have id set as String instead of UUID? cc @tomazfernandes

@maciejwalkowiak, the issue there is that the MessagingMessageHeaders inherits from MessageHeaders from Spring, and that one requires an UUID type in the constructor.

Might be worth raising with the Spring Messaging team?

In the meantime, I think we can make the solution simpler if we leverage the fact that most ID-related operations are made through the MessageHeaderUtils#getId method, which already returns a String.

Instead of requiring a configuration change to support other ID types, we could simplify the logic by trying to parse the UUID, and if it fails we add the new header as suggested in the PR.

Then in the MessageHeaderUtils#getId method, we check for the header first, and return either that, or the Spring Message ID if the former is absent.

The caveat would be that for non UUID ids, the result from getting the ID header directly would be a random UUID, but I don't think there's a way around it with the existing MessageHeaders implementation, so properly documenting the behavior should suffice. And since we don't currently support that anyway, we wouldn't really need a breaking change.

What do you folks think?

jm0514 · 2026-02-20T13:07:55Z

Fail-fast: When convert-message-id-to-uuid=true (default), receiving a non-UUID message ID now throws a MessagingException with a clear error
message and instructions.
Send-side parity: SqsTemplate now handles non-UUID message IDs in send responses. SendResult.messageId() returns a deterministic UUID, and the raw
ID is available via SendResult.additionalInformation() under the rawMessageId key.
Naming consistency: Renamed Sqs_AWSMessageId → Sqs_RawMessageId and getAwsMessageId() → getRawMessageId() to be provider-neutral and consistent
across receive/send sides.
Documentation: Added Non-UUID Message IDs section in sqs.adoc and property entry in _configprops.adoc.

…nses

tomazfernandes

Hey @jm0514, thanks for the updates. Overall direction looks solid.

I have a couple of suggestions to simplify the design and reduce duplication.

tomazfernandes · 2026-03-08T16:00:07Z

...ws-autoconfigure/src/main/java/io/awspring/cloud/autoconfigure/sqs/SqsAutoConfiguration.java

-		public MessagingMessageConverter<Message> messageConverter(ObjectProvider<JsonMapper> jsonMapperProvider) {
-			JsonMapper jsonMapper = jsonMapperProvider.getIfAvailable();
-			return jsonMapper != null ? new SqsMessagingMessageConverter(jsonMapper)
+		public MessagingMessageConverter<Message> messageConverter(ObjectProvider<JsonMapper> jsonMapperProvider,


Currently the auto-config manually creates a SqsHeaderMapper and sets the flag on it. Instead, let's add convertMessageIdToUuid as a property on both SqsContainerOptions and SqsTemplateOptions, so auto-config just does:

factory.configure(options -> options.convertMessageIdToUuid(sqsProperties.getConvertMessageIdToUuid())); builder.configure(options -> options.convertMessageIdToUuid(sqsProperties.getConvertMessageIdToUuid()));

This keeps the configuration surface consistent between container and template, removes the manual SqsHeaderMapper creation from auto-config, and gives programmatic users (without auto-config) a clean way to set it through the standard options API.

Thanks for the great suggestion! This makes the configuration much cleaner and consistent with the existing patterns.

Applied in 1d32b0c. Moved convertMessageIdToUuid to both SqsContainerOptions and SqsTemplateOptions, so auto-config now uses factory.configure() and builder.configure() instead of manually creating SqsHeaderMapper.
Added getHeaderMapper() to AbstractMessagingMessageConverter to propagate the option to the header mapper.

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/support/converter/SqsHeaderMapper.java

tomazfernandes

@jm0514, thanks for the updates. I left a few comments, we're getting closer.

The main point is that there's a mismatch between what Spring Messaging exposes, which is a UUID-based Message, and the SQS contract, which uses String ids.

Therefore we need a consistent message-id translation layer exposed consistently to users regardless of whether they're using SQS directly or another compatible implementation.

This also makes it easier to move between SQS and SQS-compatible services over time.

Also, please add @since 4.1.0 to the new classes.

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/operations/SqsTemplate.java

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/operations/SqsTemplateParameters.java

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/operations/SqsTemplate.java

...src/main/java/io/awspring/cloud/sqs/support/converter/AbstractMessagingMessageConverter.java

...ud-aws-sqs/src/main/java/io/awspring/cloud/sqs/listener/source/AbstractSqsMessageSource.java

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/operations/SqsTemplateOptions.java

…sageId

tomazfernandes

@jm0514 thanks for the changes. looks great!

I've left a couple of small comments.

Please also update:

The AbstractListenerObservation class to use the getRawMessageId method, so observability tags reflect the broker id when it's non-UUID.
The doc to reflect that the new header is added both with the flag on and off.

Thanks.

tomazfernandes · 2026-03-21T16:41:22Z

...loud-aws-sqs/src/main/java/io/awspring/cloud/sqs/support/converter/SqsMessageIdResolver.java

+		MessageHeaders withRawId = MessageHeaderUtils.addHeaderIfAbsent(headers, SqsHeaders.SQS_RAW_MESSAGE_ID_HEADER,
+				messageId);
+		if (isValidUuid(messageId)) {
+			return new MessagingMessageHeaders(withRawId, UUID.fromString(messageId));


Not critical, but we're converting UUID.fromString twice.

Perhaps the isValidUuid method could return an Optional<UUID> so we convert it only once. Method name might need to be adjusted as well.

tomazfernandes · 2026-03-21T16:43:01Z

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/operations/SqsTemplate.java

+		Map<String, Object> additionalInfo = new HashMap<>();
+		if (sequenceNumber != null) {
+			additionalInfo.put(SqsTemplateParameters.SEQUENCE_NUMBER_PARAMETER_NAME, sequenceNumber);
+		}


Looks good, but we're returning the original message which does not contain the new header.

jm0514 · 2026-03-22T06:37:48Z

@tomazfernandes Thanks for catching these — I missed the header propagation issue in SendResult while refactoring.

Here's a summary of the changes:

SqsMessageIdResolver: Renamed isValidUuid to tryParseUuid returning Optional<UUID> to avoid duplicate UUID.fromString parsing.
SqsTemplate: createSendResult now builds a new message with resolvedHeaders so Sqs_RawMessageId is included in SendResult.message().
AbstractListenerObservation: Use getRawMessageId() in Context so observation tags reflect the broker ID for non-UUID environments.
Doc: Updated to clarify that Sqs_RawMessageId header is always present regardless of the convert-message-id-to-uuid flag.

jm0514 requested review from MatejNedic, maciejwalkowiak and tomazfernandes as code owners August 9, 2025 09:15

github-actions bot added the component: sqs SQS integration related issue label Aug 9, 2025

injae-kim mentioned this pull request Aug 10, 2025

Add an option to receive MessageId as String rather than UUID #814

Open

maciejwalkowiak reviewed Aug 22, 2025

View reviewed changes

tomazfernandes added the status: waiting-for-feedback Waiting for feedback from issuer label Oct 4, 2025

github-actions bot added the type: documentation Documentation or Samples related issue label Feb 20, 2026

jm0514 added 6 commits February 21, 2026 13:43

Add an option to receive MessageId as String rather than UUID

73bb014

Add Jeongmin Kim to project contributors

1b24d21

Generate consistent UUID from Message ID instead of random UUID

787b42d

Add fail-fast for non-UUID message IDs and handle non-UUID send respo…

0eab76d

…nses

Add documentation for non-UUID message ID support

dce5a94

Rename AWSMessageId to RawMessageId for consistency

56cb5ec

jm0514 force-pushed the gh-814 branch from e9f43e3 to 56cb5ec Compare February 21, 2026 04:57

tomazfernandes requested changes Mar 8, 2026

View reviewed changes

jm0514 added 2 commits March 9, 2026 22:48

Extract SqsMessageIdResolver to consolidate message ID resolution logic

f1d7a50

Move convertMessageIdToUuid configuration to Options API

1d32b0c

tomazfernandes reviewed Mar 14, 2026

View reviewed changes

tomazfernandes removed the status: waiting-for-feedback Waiting for feedback from issuer label Mar 14, 2026

jm0514 added 3 commits March 15, 2026 23:50

Unify send and receive message ID resolution through resolveAndAddMes…

bbe8073

…sageId

Centralize message ID configuration through SqsMessageIdResolver

9ad3c89

Add @SInCE 4.1.0 and missing author metadata

3457342

tomazfernandes reviewed Mar 21, 2026

View reviewed changes

Fix send result header propagation and use raw message ID in observation

907b602

Add assertion for raw message ID header in SendResult

b4488ac

Uh oh!

Conversation

jm0514 commented Aug 9, 2025

Add configurable UUID conversion for non-AWS SQS-compatible services

📢 Type of change

📜 Description

Configuration:

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

🔮 Next steps

Uh oh!

maciejwalkowiak Aug 22, 2025

Choose a reason for hiding this comment

Uh oh!

jm0514 Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

tomazfernandes commented Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jm0514 commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tomazfernandes left a comment

Choose a reason for hiding this comment

Uh oh!

tomazfernandes Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

jm0514 Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tomazfernandes left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tomazfernandes left a comment

Choose a reason for hiding this comment

Uh oh!

tomazfernandes Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

tomazfernandes Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

jm0514 commented Mar 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tomazfernandes commented Sep 2, 2025 •

edited

Loading

jm0514 commented Feb 20, 2026 •

edited

Loading

jm0514 Mar 14, 2026 •

edited

Loading

tomazfernandes left a comment •

edited

Loading